home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / uw201.zip / ENQHELP.DOC < prev    next >
Text File  |  1991-10-12  |  15KB  |  289 lines
  1.   
  2.                       The EnQue Hypertext Help Engine
  3.                         (C) 1991 EnQue Software
  4.  
  5.  
  6.                              EnQue Software
  7.                             Route 1, Box 116C
  8.                          Pleasant Hill, MO  64080
  9.  
  10.                       24-hour BBS    : (816) 353-0991
  11.                       Fax / Voice    : (816) 329-6670
  12.                       Voice          : (816) 353-5561
  13.  
  14.  
  15. _____________________________________________________________________________
  16.  
  17.                   Using the EnQue Hypertext Help Engine
  18.  
  19.     The help engine is very easy to use due to its employment of EnQue's
  20.     new user-interface-construction toolkit, InTUItion. The help may be used
  21.     with either the keyboard or mouse.  The help files may consist of simply
  22.     ASCII files or have imbedded commands that allow for color control,
  23.     hypertext links, sound, etc.  If the files exist in the current
  24.     directory, that file is accessed, otherwise, the help engine looks in the
  25.     path set by the environment variable ENQHELP.  To set this, add a line to
  26.     your autoexec.bat file that looks something like this:
  27.  
  28.     "set ENQHELP=C:\BORLANDC\ENQUE"
  29.  
  30.     To invoke the help engine, type 
  31.   
  32.   "enqhelp filename mode search [sx sy ex ey]"
  33.   
  34.   where the filename is the first file the help engine should access. The
  35.     mode parameter tells the help engine to either read the word under the
  36.     flashing cursor (1) or use the "search" keyword (0).  If you are running
  37.     help within Borland's compilers, setting help up as a Transfer program
  38.     allows you to pull help up for UltraWin/InTUItion functions.  See
  39.     "Setting up a transfer program" below. The parameters sx, sy, ex, and ey
  40.     are screen coordinates for the window that will be used by help.  Default
  41.     values can be used (1, 4, 78, 20) if no parameters are specified.  The
  42.     help window must be either wider than 64 characters, or taller than 14.
  43.     This is to allow for the dialog interface buttons and sliders.  If the
  44.     values are out of range or the file does not exist, the help engine will
  45.     return.
  46.  
  47.     Once active, you can scroll around the help file much like an editor.
  48.     UP, DOWN, LEFT, RIGHT, HOME, END, PgUp, PgDn, Ctrl-PgUp, Ctrl-PgDn allow
  49.     you to move around the file.  If the file is wider than the help window
  50.     you can scroll horizontally as well as vertically. The buttons operate as
  51.     follows.  
  52.  
  53.   Search   - [Alt-S] pulls up a dialog to allow you to search for a specific
  54.              word or phrase.
  55.   Repeat   - [Alt-R] finds the next occurrence specified by Search.
  56.   <<<      - [Shift-Tab] key moves to the previous keyword.
  57.   >>>      - [Tab] moves to the next keyword.
  58.   Previous - [Alt-P] moves to the previously active keyword.
  59.   Index    - [Alt-I] moves to the original starting place.
  60.   Quit     - [Alt-Q] quits the help program.
  61.  
  62.     If you are using a mouse, clicking on the button, sliders, close box,
  63.     (upper left corner), or keyword will activate the function.
  64.  
  65.     To move to a keyword, you can use the tab keys or cursor keys to move
  66.     to the desired word.  The keyword will hilite.  Pressing enter or double
  67.     clicking on this word will take you to additional information on this
  68.     topic.  Pressing Alt-P (previous) will take you back one level.
  69.  
  70.     To search for a specific word/phrase, press Alt-S or click on Search.
  71.     This pulls up a dialog box.  To enter the word/phrase, press Alt-S again
  72.     or click on the string following the word Search.  Type in the
  73.     word/phrase and press Alt-O or click on OK.  The default search will
  74.     search forward from the current cursor location.  The direction and scope
  75.     can be changed by clicking on the appropriate check box or pressing the
  76.     desired hot-key.
  77.  
  78.   Forward   - [Alt-F] sets the search direction to forward.
  79.   Backward  - [Alt-B] sets the search direction to backwards.
  80.   From Csr  - [Alt-R] search from current cursor position.
  81.   Global    - [Alt-G] search from start of file.
  82.   Case      - [Alt-C] if off, case is ignored.
  83.   Quit      - [Alt-Q] abort the current search dialog.
  84.   OK        - [Alt-O] accept parameters and find first word. 
  85.  
  86.   Thats basically it!
  87. _____________________________________________________________________________
  88.  
  89.                     Setting up a Transfer Program
  90.  
  91.     To use the help engine as a transfer program from the Borland
  92.     Compilers, edit the transfer parameters as normal (see the Borland
  93.     Documentation) and for the command line parameters be sure to type
  94.     $NOSWAP as the first command.  An example for an EGA 43 row screen would
  95.     be "$NOSWAP uw_help0.hlp 1 1 20 78 40". 
  96.  
  97.     If you would like the help engine to "move" directly to the function
  98.     that your cursor points to, load the tiny TSR tckbd.com before entering
  99.     the compiler.  This is a hook that allows the help engine to read the
  100.     word that the cursor points to and search for when invoked.  It is a good
  101.     idea to call tckbd.com from you autoexec.bat.  Note that the Borland
  102.     compiler required you to set up the transfer program for each project
  103.     file.
  104.   
  105. _____________________________________________________________________________
  106.  
  107.                          Creating Your Own Help Files
  108.  
  109.   Overview:
  110.     The help commands are structured much like a "C" function call with a
  111.     few restrictions.  The command must be preceded by a ` character, and no
  112.     white space is allowed within the command.  All commands are stripped
  113.     from the help display.  A line within the help text file can contain
  114.     multiple commands and can be up to 255 characters in length.  Keep in
  115.     mind that the displayed width may be less since commands are stripped.
  116.     Also note that no commands are required; the help may simply consist of
  117.     ASCII text that is linefeed or carriage return/linefeed delimited.  These
  118.     commands are designed to allow you to enhance your help files and add
  119.     powerful hypertext capabilities. 
  120.  
  121.     Since the help files are simply ASCII, they can be edited with
  122.     virtually any text editor.  The help engine will accept and display the
  123.     extended character set if desired and your editor allows the inclusion of
  124.     these characters.  This allows you to create borders, etc, within your
  125.     help files.  The drawback to ASCII files is a small sacrifice in speed
  126.     when reading/parsing them.  However, by keeping your help files
  127.     relatively small, (to conserve memory as much as for speed), this
  128.     drawback is all but unnoticable.
  129. _____________________________________________________________________________
  130.  
  131.   KEYWORD:  `keyword(word,search string);
  132.     There are three forms of the keyword command.  The first specifies the
  133.     actual keyword followed by a search string.  Both the keyword and the
  134.     search string can consist of several words (up to 80 characters).  In
  135.     this form, the search string must reside in the same file as the keyword
  136.     command.  It can be located anywhere in the file and should be unique.
  137.     It is good practice to use a character or sequence of characters in the
  138.     search string that will not commonly occur in the text in order to assure
  139.     this uniqueness. For example:
  140.     
  141.     `keyword(File System,/// The DOS File System);
  142.     
  143.       Here we use three / to insure the uniqueness of the search string.
  144.     Note that the keyword and search string can be different.
  145.  
  146.     The second form is like the first but include a modifier in front of
  147.     the search string.  This modifier, enclosed in brackets, specifies the
  148.     file in which the search string exists. For example:
  149.     
  150.     `keyword(DOS,[dos.hlp]/// DOS);
  151.     
  152.       This works the same as the example above except that the file dos.hlp
  153.     will no be loaded into the help engine and the search string "/// DOS"
  154.     will be located.
  155.  
  156.     The third form is similar to the other two in form but different in
  157.     action. When the user moves to this keyword and presses <Enter>, the
  158.     second parameter is used as a DOS command and executed.  For example:
  159.     
  160.     `keyword(DIR,{dir c:});
  161.     
  162.       When selected, this keyword will execute the DOS command "dir c:".
  163.     This is useful for creating menus, shells, etc.
  164. _____________________________________________________________________________
  165.  
  166.   COLOR:  `color(foreground string,background string);
  167.     There are a number of color control commands that allow you to
  168.     personalize your help files. Often, only one or two are used.  The first
  169.     and most common is the color command.  Two parameters specify the
  170.     foreground and background colors.  For example `color(RED,LIGHTGRAY);
  171.     Sixteen colors are available for each.  Knowledge of the PC text
  172.     attribute structure is recommended but not required.  The colors are as
  173.     follows:
  174.  
  175.                     Normal           High Intensity
  176.                     -------          --------------
  177.                     0 BLACK           8 DARKGRAY     
  178.                     1 BLUE            9 LIGHTBLUE    
  179.                     2 GREEN          10 LIGHTGREEN   
  180.                     3 CYAN           11 LIGHTCYAN    
  181.                     4 RED            12 LIGHTRED     
  182.                     5 MAGENTA        13 LIGHTMAGENTA 
  183.                     6 BROWN          14 YELLOW       
  184.                     7 LIGHTGRAY      15 WHITE        
  185.  
  186.     The high intensity will cause the text to blink if used as the
  187.     background color unless the blink bit is disabled.  In addition to these
  188.     16 colors, DEFAULT can be specified for either/both foreground or
  189.     background.  This will restore the color to its default state. (As
  190.     specified by color_default or the program if color_default is not used)
  191.     For example if our default colors are WHITE on BLACK and we specify
  192.     `color(RED,BLACK);  followed later by `color(DEFAULT,GREEN); we will then
  193.     have WHITE on GREEN.
  194. _____________________________________________________________________________
  195.  
  196.   CO:  `co(foreground #,background #);
  197.     This command operates identically to color but is a short form version
  198.     and is preferable where many color commands are used.  In this form we
  199.     specify the colors with their decimal value 0-15 instead of a much longer
  200.     text string.  For example, instead of `color(LIGHTGRAY,GREEN); we would
  201.     have `co(7,2);  If many commands exists in a file this saves both space
  202.     and time when the text is displayed, as the help engine does not have to
  203.     search for the color string.  This also accepts default parameters but in
  204.     this form you simply use a ? i.e. `co(?,3);  In addition, this form
  205.     allows you to completely exclude the parameters and restore the default
  206.     foreground and background with the simply call `co();  This is preferable
  207.     since it then allows you greater flexibility is changing the default
  208.     colors without having to search and replace all color commands that
  209.     restore the defaults.
  210. _____________________________________________________________________________
  211.  
  212.   CK:  `ck(foreground #,background #);
  213.     This command is the same as co except that the first character
  214.     following the command is displayed in the attribute specified by the
  215.     color_first_char command (or the program if color_first_char is not
  216.     used).  This is used internally by the help engine and is not normally
  217.     needed.
  218. _____________________________________________________________________________
  219.  
  220.   COLOR_DEFAULT:  `color_default(foreground string,background string);
  221.     This command specifies the default foreground and background colors.
  222.     This command is not required unless the program default is to be
  223.     overidden. If it is used, it should be on the first line in the help
  224.     file.
  225. _____________________________________________________________________________
  226.  
  227.   COLOR_FIRST_CHAR:  `color_first_char(foreground string,background string);
  228.     This command specifies the color of the first character of all
  229.     keywords. This command is not required unless the program default is to
  230.     be overidden. If it is used, it should be on the first line in the help
  231.     file.
  232. _____________________________________________________________________________
  233.  
  234.   COLOR_HILITE:  `color_hilite(foreground string,background string);
  235.     This command specifies the color of the keyword when the cursor selects
  236.     it. This command is not required unless the program default is to be
  237.     overidden. If it is used, it should be on the first line in the help
  238.     file.
  239. _____________________________________________________________________________
  240.  
  241.   COLOR_KEYWORD:  `color_keyword(foreground string,background string);
  242.     This command specifies the color of the keyword itself. This command is
  243.     not required unless the program default is to be overidden. If it is
  244.     used, it should be on the first line in the help file.
  245. _____________________________________________________________________________
  246.   
  247.   SOUND:  `sound(frequency,duration);
  248.     This routine causes the speaker to sound at the desired frequency for
  249.     the specified duration in clock ticks (91/second) when this line is
  250.     displayed. It is useful specifying the end of file and other important
  251.     segments within the help file.
  252. _____________________________________________________________________________
  253.  
  254.   DELAY:  `delay(duration);
  255.     This routine causes the program to pause for the specified duration in
  256.     clock ticks (91/second) when this line is displayed.
  257. _____________________________________________________________________________
  258.  
  259.   DOS:  `dos(command line);
  260.     This routine causes the DOS program to be executed when the line
  261.     containing this command is displayed.  Note that this is different from
  262.     the DOS command within a keyword, as this occurs on display, and the
  263.     keyword version only occurs if the user selects the keyword and presses
  264.     <Enter>.
  265. _____________________________________________________________________________
  266.  
  267.   BLINK:  `blink(state);  (EGA/VGA only)
  268.     This routine turns the blink enable bit on or off depending on "state".
  269.     To disable blinking, use 0 , to enable, use 1.  Turning this bit off
  270.     allows all 256 possible color combinations to be used without the high
  271.     intensity background colors blinking.  If this function is used, it
  272.     should be on the first line in the help file.
  273. _____________________________________________________________________________
  274.  
  275.   FONT:  `font(fontname,block);  (EGA/VGA only)
  276.     This routine loads the desired font into the specified "block".  Block
  277.     0 is the primary font, block 1 is the font selected by usig the high
  278.     intensisty colors.  (See UltraWin documentation for more details). If
  279.     this function is used, it should be on the first line in the help file.
  280.     Once the font command is encountered, it is "disable" so that each time
  281.     the line is displayed the font will not be reloaded and the screen reset.
  282. _____________________________________________________________________________
  283.  
  284.   TAB:  `tab(value);
  285.       This routine sets the tab size for the given file.  The default value
  286.     is 2.  If this function is used, it should be on the first line in the
  287.     help file. (Or before any tabs occur).
  288.  
  289.